Plotting API

UXarray provides a fully-fledged plotting API for visualizing unstructured grids.

This notebook introduces how to interact with plotting methods directly though UXarray data structures.

See also:

This notebook acts as an introduction into using the UXarray plotting API. Please refer to the following notebooks in this chapter for a detailed overview of visualization techniques for different purposes (e.g. Grid Topology, Polygons

UXarray Plotting API Design

Before looking into the plotting API details, let us have a look at the current snapshot of the API design from an Unified Modelling Language (UML)-like standpoint:

UXarray Plotting API Design

Key takeaways from this design are that:

  • UXarray supports multiple unstructured grid formats and represent them all in a unified manner as we mentioned multiple times before. This allows us to provide our visualization functionality for all those supported grid formats.

  • Each Uxarray data structure (i.e. Grid, UxDataset, UxDataArray) has its own .plot accessor to provide visualization functions in the user API.

  • The visualization functionality through these .plot accessors use HoloViz packages’ plotting functions, wrapping them in a way to exploit all the information that comes from unstructured grids (e.g. connectivity) and provide our unstructured grids-specific functions in the most convenient way for the user.

  • Grid additionally provides conversion functions that generate SpatialPandas.GeoDataFrame as well as Matplotlib.PolyCollection and Matplotlib.LineCollection data structures to be visualized in HoloViz packages and Matplotlib, respectively, at the user’s own convenience.

Now, we can look into technical details along with some code snippets.

Imports

import uxarray as ux

file_dir = "../../meshfiles/"
grid_filename = file_dir + "oQU480.grid.nc"
data_filename = file_dir + "oQU480.data.nc"

grid = ux.open_grid(grid_filename)
uxds = ux.open_dataset(grid_filename, data_filename)

Grid Plotting

For visualizing the topology (i.e. geometry) of an unstructured grid, plotting is done through a Grid Instance

grid.plot(title="Default Grid Plot")

You can call specific plotting routines through the plot accessor

grid.plot.nodes(title="Grid Node Plot")

If you have a UxDataset or UxDataArray, you can access the Grid through the uxgrid attribute.

uxds.uxgrid.plot(title="Default Grid Plot through uxgrid attribute")

UxDataset & UxDataArray Plotting

For visualizing data variables, plotting is done through a UxDataArray instance.

uxds["bottomDepth"].plot(title="Default UxDataArray Plot")

As was shown with a Grid, you can call specific plotting routines through the plot accessor

uxds["bottomDepth"].plot.points(title="UxDataArray Point Plot")

Plotting a UxDataset currently not supported

uxds.plot()

/home/runner/miniconda3/envs/unstructured-grid-viz-cookbook-dev/lib/python3.10/site-packages/uxarray/plot/accessor.py:471: UserWarning: Plotting for UxDataset instances not yet supported. Did you mean to plot a data variable, i.e. uxds['data_variable'].plot()
  warnings.warn(

Customization

UXarray’s plotting API is built around the Holoviews Python package. For details about customizing plots, expected parameters, and other features, you can refer to their documentation. Below are brief examples on how to customize plots.

Figure Size

grid.plot(width=500, height=250)

Creating Subplots

(
    grid.plot(width=500, height=250, color="Black")
    + grid.plot(width=500, height=250, color="Blue")
    + grid.plot(width=500, height=250, color="Red")
    + grid.plot(width=500, height=250, color="Green")
).cols(2)

(
    grid.plot(width=500, height=250, color="Black")
    + grid.plot(width=500, height=250, color="Blue")
    + grid.plot(width=500, height=250, color="Red")
    + grid.plot(width=500, height=250, color="Green")
).cols(1)
On this page